Embabel Agent Documentation/com.embabel.agent.core

Package-level declarations

Types

abstract class AbstractAgentProcessRepository : AgentProcessRepository

Abstract base class for AgentProcessRepository implementations that enforces ephemeral process handling.

interface Action : DataFlowStep, ConditionAction, ActionRunner, DataDictionary, ToolGroupConsumer

Core Action model in Agent system. An individual action step used in an Agent Not intended for direct use by application code. User applications should use the annotation programming model with @Agentic and @Action or the Kotlin DSL, or a non-code representation such as YML.

ActionException

open class ActionException(message: String, cause: Throwable? = null) : RuntimeException

Base class for action execution exceptions with built-in retry classification.

ActionInvocation

data class ActionInvocation(val actionName: String, val timestamp: Instant = Instant.now(), val runningTime: Duration)

History element

ActionMetadata

data class ActionMetadata(val name: String, val description: String, val inputs: Set<IoBinding>, val outputs: Set<IoBinding>, val preconditions: EffectSpec, val effects: EffectSpec, val canRerun: Boolean, val readOnly: Boolean, val qos: ActionQos)

Serializable action metadata

ActionQos

data class ActionQos(val maxAttempts: Int = 5, val backoffMillis: Long = 10000, val backoffMultiplier: Double = 5.0, val backoffMaxInterval: Long = 60000, val idempotent: Boolean = false) : RetryProperties

Quality of service requirements for an action

ActionRetryPolicy

enum ActionRetryPolicy : Enum<ActionRetryPolicy>

Retry policy selector for an action.

ActionRunner

interface ActionRunner

ActionSource

interface ActionSource

ActionStatus

open class ActionStatus(val runningTime: Duration, val status: ActionStatusCode) : OperationStatus<ActionStatusCode>

Status of action execution. Concrete results of running the action will be side effects: typically, changes to the ProcessContext blackboard. This just indicates what happened.

ActionStatusCode

enum ActionStatusCode : Enum<ActionStatusCode>

Status code for execution of an action

ActionVoidResult

object ActionVoidResult

Sentinel object added to the blackboard when an action completes without producing a result (null, Unit, or Void return). This invalidates any @Trigger precondition that was satisfied before the action ran.

Agent

data class Agent(val name: String, val provider: String, val version: <Error class: unknown class> = Semver(), val description: String, val conditions: Set<Condition> = emptySet(), val actions: List<Action>, val goals: Set<Goal>, val stuckHandler: StuckHandler? = null, val opaque: Boolean = false, val domainTypes: Collection<DomainType> = mergeTypes( agentName = name, defaultDataTypes = emptyList(), actions = actions, )) : AgentScope

An agent defines a set of actions and conditions that enable planning.

AgentMetadata

data class AgentMetadata(val name: String, val provider: String, val version: <Error class: unknown class>, val description: String, val goals: Set<Goal>, val actions: List<ActionMetadata>, val conditions: Set<String>)

Safely serializable agent metadata

AgentPlatform

interface AgentPlatform : AgentScope

An AgentPlatform can run agents. It can also act as an agent itself, drawing on all of its agents as its own actions, goals, and conditions. An AgentPlatform is stateful, as agents can be deployed to it. See TypedOps for a higher level API with typed I/O. Typically, there is one AgentPlatform per Spring Boot application, with agents discovered by classpath scanning for @Agent annotations, but this is not a requirement.

AgentProcess

interface AgentProcess : Blackboard, OperationStatus<AgentProcessStatusCode> , LlmInvocationHistory, EmbeddingInvocationHistory

Run of an agent

AgentProcessCallback

interface AgentProcessCallback

Callback interface for interleaving logic with the lifecycle of an AgentProcess and its actions.

AgentProcessRepository

interface AgentProcessRepository

Repository for agent processes.

AgentProcessStatusCode

enum AgentProcessStatusCode : Enum<AgentProcessStatusCode>

Stuck means we failed to find a plan from here

AgentProcessStatusReport

data class AgentProcessStatusReport(val id: String, val status: AgentProcessStatusCode, val timestamp: Instant, val runningTime: Duration) : OperationStatus<AgentProcessStatusCode>

Safely serializable status for agent processes.

AgentScope

interface AgentScope : GoalSource, ConditionSource, ActionSource, DataDictionary, AgentScopeBuilder

Defines the scope of an agent or agents: Goals, conditions and actions. Both Agents and AgentPlatforms are AgentScopes.

AgentSystemStep

interface AgentSystemStep : ConditionStep, Operation

AllowedRelationship

data class AllowedRelationship(val from: DomainType, val to: DomainType, val name: String, val description: String = name, val cardinality: Cardinality, val metadata: Map<String, String> = emptyMap())

Represents a relationship between two domain types.

Bindable

interface Bindable

Allows binding and retrieval of objects using Kotlin operator functions and traditional get/set

Blackboard

interface Blackboard : Bindable, MayHaveLastResult

A Blackboard is how an AgentProcess maintains context. Blackboard operations are threadsafe. Blackboards are immutable in the sense that once an object has been added it cannot be removed. However, objects can be hidden so they are no longer visible to retrieval operations (e.g. driving planning).

BlackboardUpdater

fun interface BlackboardUpdater

Callback to update the blackboard before replanning. Defined as a fun interface for Java interoperability.

Budget

data class Budget constructor(val cost: Double = DEFAULT_COST_LIMIT, val actions: Int = DEFAULT_ACTION_LIMIT, val tokens: Int = DEFAULT_TOKEN_LIMIT)

Budget for an agent process.

Cardinality

enum Cardinality : Enum<Cardinality>

Semantics of holding the value for the property

ComputedBooleanCondition

class ComputedBooleanCondition(val name: String, val cost: <Error class: unknown class> = 0.0, evaluator: (context: OperationContext, condition: Condition) -> Boolean) : Condition

Convenient class for a condition that evaluates to true or false.

Condition

interface Condition : ConditionMetadata

A Condition is a named, well known predicate that can be evaluated and reused across multiple Actions.

ConditionMetadata

interface ConditionMetadata : Operation

ConditionSource

interface ConditionSource

Context

interface Context

Implemented by instances that can hold longer lasting state than a blackboard. Offers the same ability to add an object or bind it to a key.

ContextId

value class ContextId(val value: String)

Id of a context.

CoreToolGroups

object CoreToolGroups

Core tool groups exposed by the platform These should be supported in any AgentPlatform instance.

CreationPermitted

@Target(allowedTargets = [AnnotationTarget.CLASS])

annotation class CreationPermitted(val value: Boolean)

If this value is false, we cannot create new instances of this type: For example, it's a reference.

DataDictionary

interface DataDictionary

Exposes access to a set of known data types

DataFlowStep

interface DataFlowStep : AgentSystemStep

Step that takes data as input and produces data as output.

Delay

enum Delay : Enum<Delay>

DomainInstance

interface DomainInstance

A blackboard value whose identity is a DomainType (typically a DynamicType declared in YAML, not a JVM class) plus a property map carrying the actual data.

DomainType

sealed interface DomainType

Type known to the Embabel agent platform. May be backed by a domain object or ba dynamic type. Supports inheritance.

DomainTypePropertyDefinition

data class DomainTypePropertyDefinition constructor(val name: String, val type: DomainType, val cardinality: Cardinality = Cardinality.ONE, val description: String = name, val metadata: Map<String, String> = emptyMap()) : PropertyDefinition

Property that holds a nested DomainType Represents a relationship to another domain object

DynamicType

data class DynamicType(val name: String, val description: String = name, val ownProperties: List<PropertyDefinition> = emptyList(), val parents: List<DomainType> = emptyList(), val creationPermitted: Boolean = true) : DomainType

Simple data type. Enables interop with non-JVM types.

EarlyTermination

class EarlyTermination(val agentProcess: AgentProcess, val error: Boolean, val reason: String, val policy: EarlyTerminationPolicy) : AbstractAgentProcessEvent

Event triggered when an agent process is terminated early by a policy.

EarlyTerminationPolicy

interface EarlyTerminationPolicy

Enables early termination of an agent process.

EmbeddingInvocation

data class EmbeddingInvocation(val embeddingMetadata: <Error class: unknown class>, val usage: Usage, val agentName: String? = null, val timestamp: Instant, val runningTime: Duration)

Invocation we made to an EmbeddingServiceMetadata. Mirror of LlmInvocation for embedding services.

EmbeddingInvocationHistory

interface EmbeddingInvocationHistory

History of embedding invocations made during an agent process or other embedding-consuming component (e.g. ingestion pipelines, RAG indexing).

Export

data class Export(val name: String? = null, val remote: Boolean = false, val local: Boolean = true, val startingInputTypes: Set<Class<*>> = emptySet())

Metadata describing how a goal will be exported

Goal

data class Goal(val name: String, val description: String, val pre: Set<String> = emptySet(), val inputs: Set<IoBinding> = emptySet(), val outputType: DomainType?, val value: CostComputation = { 0.0 }, val tags: Set<String> = emptySet(), val examples: Set<String> = emptySet(), val export: Export = Export()) : ConditionGoal, AgentSystemStep

Agent platform goal. Exposes GOAP metadata.

GoalSource

interface GoalSource

Identities

data class Identities constructor(val forUser: User? = null, val runAs: User? = null)

Identities associated with an agent process.

InjectedType

interface InjectedType : Operation

Access to agent infrastructure via injected parameter.

InProcess

interface InProcess

Superclass for events that relate to an AgentProcess

IoBinding

value class IoBinding(val value: String)

Binding definition of form name:Type If name is omitted, it is assumed to be 'it' Used to build preconditions from input and output bindings. Default name ("it") has a special meaning. It will be satisfied by an instance of the correct type being bound to "it", but also by the final result of the action having the correct type.

JvmType

data class JvmType constructor(val className: String) : DomainType

Typed backed by a JVM object It's good practice to annotate classes with @JsonClassDescription for better descriptions: otherwise, only the simple class name will be used. Use the @CreationPermitted annotation to indicate whether new instances of this type can be created. Default is true.

LlmInvocation

data class LlmInvocation(val llmMetadata: <Error class: unknown class>, val usage: Usage, val agentName: String? = null, val timestamp: Instant, val runningTime: Duration)

Invocation we made to an LLM

LlmInvocationHistory

interface LlmInvocationHistory

History of LLM invocations made during an agent process.

LlmVerbosity

interface LlmVerbosity

Control how much detail to log from LLM interactions.

MayHaveLastResult

interface MayHaveLastResult

NamedPropertyDefinition

interface NamedPropertyDefinition : PropertyDefinition

Property definition that refers to a named type, usually a simple type.

NonRetryable

interface NonRetryable

Marker interface indicating that an operation should NOT be retried on failure.

Operation

sealed interface Operation

Named operation in agent system: Action, Goal or Condition

OperationStatus

interface OperationStatus<S : Enum<S>>

Status of an agent or action

ProcessContext

data class ProcessContext(val processOptions: ProcessOptions = ProcessOptions(), platformServices: PlatformServices, val outputChannel: OutputChannel = platformServices.outputChannel + processOptions.outputChannel, val agentProcess: AgentProcess) : LlmOperations, AgenticEventListener

Process state and services. Created by the platform, not user code.

ProcessControl

data class ProcessControl constructor(val toolDelay: Delay = Delay.NONE, val operationDelay: Delay = Delay.NONE, val earlyTerminationPolicy: EarlyTerminationPolicy = EarlyTerminationPolicy.maxActions(100))

Controls how an AgentProcess is run. Prevents infinite loops, enforces budget limits, and manages delays.

ProcessOptions

data class ProcessOptions constructor(val contextId: ContextId? = null, val identities: Identities = Identities(), val blackboard: Blackboard? = null, val verbosity: Verbosity = Verbosity(), val budget: Budget = Budget(), val processControl: ProcessControl = ProcessControl( toolDelay = Delay.NONE, operationDelay = Delay.NONE, earlyTerminationPolicy = budget.earlyTerminationPolicy(), ), val prune: Boolean = false, val ephemeral: Boolean = false, val listeners: List<AgenticEventListener> = emptyList(), val outputChannel: OutputChannel = DevNullOutputChannel, val plannerType: PlannerType = PlannerType.GOAP, val toolCallContext: ToolCallContext = ToolCallContext.EMPTY)

How to run an AgentProcess Create and customize using withers

PropertyDefinition

sealed interface PropertyDefinition

PropertyValidationRule

interface PropertyValidationRule

Type-safe validation rule interface for property validation. Implement this interface to create custom validation rules.

ReplanRequestedException

class ReplanRequestedException constructor(val reason: String, val blackboardUpdater: BlackboardUpdater = BlackboardUpdater {}) : RuntimeException, ToolControlFlowSignal

Exception thrown by a tool to signal that the tool loop should terminate and the agent should replan based on the updated blackboard state.

Retryable

interface Retryable

Marker interface indicating that an operation should be retried on failure.

Semantics

@Target(allowedTargets = [AnnotationTarget.FIELD, AnnotationTarget.PROPERTY])

annotation class Semantics(val value: Array<With> = [])

Defines semantic metadata for a property. This annotation allows attaching arbitrary key-value metadata to properties, which can be used for semantic processing such as proposition extraction, relationship mapping, and natural language generation.

ToolConsumer

interface ToolConsumer : ToolSpecConsumer, ToolGroupConsumer

Allows consuming tools and exposing them to LLMs. Interface allowing abstraction between tool concept and specific tools.

ToolGroup

interface ToolGroup : ToolPublisher

A group of tools to accomplish a purpose, such as web search. Introduces a level of abstraction over tools.

ToolGroupConsumer

interface ToolGroupConsumer

ToolGroupDescription

interface ToolGroupDescription

ToolGroupMetadata

interface ToolGroupMetadata : ToolGroupDescription

Metadata about a tool group. Interface as platforms may extend it

ToolGroupPermission

enum ToolGroupPermission : Enum<ToolGroupPermission>

ToolGroupRequirement

data class ToolGroupRequirement(val role: String, val requiredToolNames: Set<String> = emptySet(), val terminationScope: TerminationScope? = null)

Specifies a tool group that a tool consumer requires.

ToolGroupResolution

data class ToolGroupResolution(val resolvedToolGroup: ToolGroup?, val failureMessage: String? = null)

Resolution of a tool group request

ToolPublisher

interface ToolPublisher : ToolSpec

Publisher interface for tools using the framework-agnostic Tool interface.

ToolSpec

interface ToolSpec

Specification for exposing tools using the framework-agnostic Tool interface.

ToolSpecConsumer

interface ToolSpecConsumer : ToolSpec

Consumer interface for tools using the framework-agnostic Tool interface.

Usage

data class Usage(val promptTokens: Int?, val completionTokens: Int?, val nativeUsage: Any?)

LLM usage data

ValidatedPropertyDefinition

data class ValidatedPropertyDefinition constructor(val name: String, val type: String = "string", val cardinality: Cardinality = Cardinality.ONE, val description: String = name, val metadata: Map<String, String> = emptyMap(), val validationRules: List<PropertyValidationRule> = emptyList()) : NamedPropertyDefinition

Value property with type-safe validation rules. Extends ValuePropertyDefinition with compile-time checked validation.

ValuePropertyDefinition

data class ValuePropertyDefinition constructor(val name: String, val type: String = "string", val cardinality: Cardinality = Cardinality.ONE, val description: String = name, val metadata: Map<String, String> = emptyMap()) : NamedPropertyDefinition

Simple value property, such as string, int, boolean, etc. Not necessarily a scalar, as cardinality may be LIST or SET.

Verbosity

data class Verbosity constructor(val showPrompts: Boolean = false, val showLlmResponses: Boolean = false, val debug: Boolean = false, val showPlanning: Boolean = false) : LlmVerbosity

Controls log output.

With

@Target(allowedTargets = [])

annotation class With(val key: String, val value: String)

A key-value pair for semantic metadata. Used within @Semantics to define semantic properties of a field.

Properties

TYPE_LABELS_KEY

const val TYPE_LABELS_KEY: String

Reserved key on a Map<String, Any?> blackboard value carrying the flattened ancestor type names (self + parents + grandparents…), used by satisfiesType to match preconditions on parent types. Value is an Iterable<String> of names. Optional — when absent, only TYPE_NAME_KEY is consulted, which means the map only satisfies its own type, not its ancestors. Emitters that know the type's parent chain should populate this so the value behaves like a DomainInstance for inheritance.

TYPE_NAME_KEY

const val TYPE_NAME_KEY: String

Reserved key on a Map<String, Any?> blackboard value carrying its declared DomainType name. Lets a value participate in type-aware matching (satisfiesType) without a carrier class — useful for pack-authored tools, sandbox script returns, and other emitters that don't want to define a Kotlin class. Value is the type's DomainType.name.

Functions

count

inline fun <T> Blackboard.count(): Int

Count entries of the given type

findTypeByNameOrSimpleName

fun Collection<DomainType>.findTypeByNameOrSimpleName(name: String): DomainType?

Look up a DomainType by exact DomainType.name (FQN or whatever the type was registered under) and fall back to a simple-name match (name.substringAfterLast('.')). Lets callers refer to a type by its natural simple name in YAML / spec form even though the platform registered the JVM-backed type under its FQN. Returns null so callers can chain other lookups (classpath, etc.) before throwing.

last

inline fun <T> Blackboard.last(): T?

Last entry of the given type, if there is one

objectsOfType

inline fun <T> Blackboard.objectsOfType(): List<T>

Return all entries of a specific type

resultOfType

inline fun <O> AgentProcess.resultOfType(): O

Convenience function to get the result of a specific type

satisfiesType

fun satisfiesType(boundInstance: Any, type: String): Boolean

Does the bound instance satisfy the type.